Introduction
Welcome to PyReports. In PyReports two main categories are containers and objects. Containers are things that contain objects. Objects are images, text, code etc things that you would want to put in your report. Containers could reports, sections, grids, folds etc. Both the containers and the objects derive from what is called a _Node giving the report a tree structure with well defined parent child relation between its containers and objects. The root of the report tree is the report container itself where as its leaves will be the objects (objects cant contain other objects and therefore can not be parents to further nodes). As you will see below, Nodes have context managers which allow to type reports easily without having to specify the parent and child relations explicitly. It will be guessed from context. So at the heart of report typing lies the _Context object in objects.py from which the _Node derives. Class methods and variables of _Context track the creation of containers and objects and establish the necessary associations between them.
Basics
With PyReports, the suggested workflow is to use contexts (i.e with statements) to create new containers. With in any context, any object that is used directly becomes attached to that container whether it be a section, grid or any other object from containers.py. As an example one can write:
with report('My Report'): # create a report
with Section('Introduction'): # create a section
Txt('Hello world') # put a text in that section
with Grid(2,1): # put a grid with 2 cols and 1 row in section
Img(path1) # put an Img in the grid
Img(path2) # put a second Img in the grid
One can directly attach a container to a parent via statements such
as
Section('Introduction', parent=report)
when needed. By the way there is a better way to display
code using Cde object:
with report('My Report'): # create a report
with Section('Introduction'): # create a section
Txt('Hello world') # put a text in that section
with Grid(2,1): # put a grid with 2 cols and 1 row in section
Img(path1) # put an Img in the grid
Img(path2) # put a second Img in the grid
When displaying text, newlines are not taken into account and long
lines get wrapped (maximum of 100 px or 50% of device width which
can be changed via the configuration files, see section Styling Almost
everything). Empty lines do appear as they are though. So to have an
empty line in your text, you do not needs to insert
manually.
It will be done automatically such as the empty line that is
right below this sentence.
One can also itemize text by starting the line with -, 1-,2-, 1.,2.
etc such as:
-item1
-item2
or
1-item1
2-item2
Not that indents at the beginning of each line are managed automatically
relative to the text they are in.
Codes can be displayed using Cde object which has syntax highlighting
and is automatically formatted to appear as it is on the editor.
By the way you can print what the report looks like using report.summary.
It will show the contets of the report up to the point of printing:
REPORT (Test Report)
├───SECTION (Introduction)
└───SECTION (Basics)
You can put single images using the Img tag. Images are directly embedded to the html (unless you turn that off while creating the image) so you can share your beatiful reports with your friends without having to share the images and such. You can add titles to images but more formatting requires using Grids which is explained in the Grid Layouts section.
Planescape is awesome
Beware there be quotes
When you write formatted text or code, there is some internal machinery going on to decide when to have linebreaks and this depends on where are the newline characters in text. However not every newline character could mean that there should be a newline. For instance you might be displaying a code which has a variable equated to a string that has newline in it. Therefore newlines inside quotation marks are disregarded when displaying code. This means tracking when a quote has been opened and it has been closed. We assume that all strings in code are flanked by double quotes, single quotes can be reliably parsed in a similiar way due to python`s triple quote formatted strings where newlines should be considered as they are. So consider the following cases, first wrong, second correct:
'''
Hello world.py
I am not a quote and I am not not a quote.
What am I??
'''
string1 = "hello world I am here"
string2 = '''
Formatting inside formatting,
what a head ache
'''
a = 5
'''
Hello world.py
I am not a quote and I am not not a quote.
What am I??
'''
string1 = 'hello world
I am here'
string2 = '''
Formatting inside formatting,
what a head ache
'''
a = 5
Grid Layouts
By using grids within grids, you can achieve any layout your heart desires. Consider for instance the following which uses two grids, one inside the other. As with single images, you can put a title to each grid element and we have done so below to make the layout more clear.
The code used for this layout is
with Grid(2,1, end=''):
Img(f'{dir_path}/image1.jpeg',scale=1.3)
with Grid(1,3,end=''):
Img(f'{dir_path}/image2.jpeg')
Img(f'{dir_path}/image3.png',scale=0.5)
Img(f'{dir_path}/image4.png',scale=0.5)
Other Containers
Apart from Reports, Sections and Grids, there are two other containers:
Tabs and Folds.
Tabs allow you to organize objects into tabs so that you only see
one of object at a time, the one whose tab is selected. As an example:
Apart from each item`s individual button, there is also the open all
button which shows all the items at the same time (fun fact: this
button is also called the Derek button. Derek hates tabulated views).
The fold allows you to hide content by folding it. It comes automatically
with the Code object (which is the only object that comes with a
preexisting parent). But you can put other stuff in folds too,
even other containers. This is a great way to suprise your friends!
